Skip to content

fix(astro): recover island hydration from transient import failures#16412

Merged
ematipico merged 6 commits into
withastro:mainfrom
0xbejaxer:fix-16341-hydration-recovery
May 6, 2026
Merged

fix(astro): recover island hydration from transient import failures#16412
ematipico merged 6 commits into
withastro:mainfrom
0xbejaxer:fix-16341-hydration-recovery

Conversation

@0xbejaxer
Copy link
Copy Markdown
Contributor

@0xbejaxer 0xbejaxer commented Apr 20, 2026

Summary

  • add astro-island import retry handling with a hash-based retry specifier so transient hydration module import failures can recover
  • dispatch a cancelable astro:hydration-error event with error context and keep default logging only when the event is not prevented
  • add an E2E regression fixture/test that validates recovery after one failed import and verifies persistent failures emit the event without unhandled page errors

Validation

Fixes #16341.

@changeset-bot
Copy link
Copy Markdown

changeset-bot Bot commented Apr 20, 2026

🦋 Changeset detected

Latest commit: 2ae3eec

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@github-actions github-actions Bot added the pkg: astro Related to the core `astro` package (scope) label Apr 20, 2026
@codspeed-hq
Copy link
Copy Markdown

codspeed-hq Bot commented Apr 20, 2026

Merging this PR will not alter performance

✅ 18 untouched benchmarks


Comparing 0xbejaxer:fix-16341-hydration-recovery (2ae3eec) with main (15fc3f6)1

Open in CodSpeed

Footnotes

  1. No successful run was found on main (8e0ff3d) during the generation of this report, so 15fc3f6 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report.

@0xbejaxer
Copy link
Copy Markdown
Contributor Author

Small update now that CI is fully green.

This PR fixes #16341 by handling island hydration import failures in astro-island with:

  • one retry path for failed component/renderer dynamic imports
  • a cancelable astro:hydration-error event with { error, componentUrl }
  • default console logging only when the event is not prevented
  • error handling in the directive callback path to avoid unhandled rejection noise

Two follow-up commits were needed during CI hardening:

  • f15add9ecf: sync lockfile for the new e2e fixture
  • 47bd822e41: stabilize the new retry e2e by waiting for hydration before asserting click behavior

All checks are now passing.

@0xbejaxer
Copy link
Copy Markdown
Contributor Author

Hi maintainers — friendly ping on this one whenever you have time.

This PR addresses the hydration import failure recovery path discussed in the issue and includes e2e coverage for both retry-success and persistent-failure event behavior.

If there’s any part you’d like reworked (implementation or test shape), I can update quickly.

0xbejaxer added a commit to 0xbejaxer/astro that referenced this pull request Apr 21, 2026
Trigger a fresh workflow run for PR withastro#16412 after an unrelated flaky Cloudflare development e2e failure on windows.

Made-with: Cursor
Retry failed hydration imports with a cache-busting specifier and emit a cancelable astro:hydration-error event so applications can recover without unhandled rejection noise.

Made-with: Cursor
Add the new e2e fixture importer to pnpm-lock.yaml so frozen-lockfile CI installs succeed.

Made-with: Cursor
Wait for island hydration before clicking in the retry test to avoid timing-dependent failures on slower CI runners.

Made-with: Cursor
Trigger a fresh CI run to verify the unrelated lint/typecheck failure is reproducible.

Made-with: Cursor
Trigger a fresh workflow run for PR withastro#16412 after an unrelated flaky Cloudflare development e2e failure on windows.

Made-with: Cursor
@0xbejaxer 0xbejaxer force-pushed the fix-16341-hydration-recovery branch from d9da665 to 622ad51 Compare April 22, 2026 10:40
Copy link
Copy Markdown
Contributor

@matthewp matthewp left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's make this just an event, no retries.

Comment thread .changeset/five-pans-applaud.md Outdated
@@ -0,0 +1,5 @@
---
'astro': patch
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a new feature so should be minor.

Also make the changeset a little more in-depth, show a code example of how you might use this.

Copy link
Copy Markdown
Contributor

@matthewp matthewp left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please make this a minor change

@matthewp matthewp added this to the 6.3 milestone May 1, 2026
Comment thread .changeset/five-pans-applaud.md Outdated
@github-actions github-actions Bot added the semver: minor Change triggers a `minor` release label May 6, 2026
Copy link
Copy Markdown
Contributor

@github-actions github-actions Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR is blocked because it contains a minor changeset. A reviewer will merge this at the next release if approved.

@ematipico ematipico dismissed stale reviews from matthewp and github-actions[bot] May 6, 2026 09:56

Addressed

@ematipico ematipico merged commit ba2d2e3 into withastro:main May 6, 2026
26 of 27 checks passed
@astrobot-houston astrobot-houston mentioned this pull request May 6, 2026
dadezzz pushed a commit to dadezzz/university_notes that referenced this pull request May 12, 2026
This PR contains the following updates:

| Package | Change | [Age](https://docs.renovatebot.com/merge-confidence/) | [Confidence](https://docs.renovatebot.com/merge-confidence/) |
|---|---|---|---|
| [astro](https://astro.build) ([source](https://github.com/withastro/astro/tree/HEAD/packages/astro)) | [`6.2.2` → `6.3.1`](https://renovatebot.com/diffs/npm/astro/6.2.2/6.3.1) | ![age](https://developer.mend.io/api/mc/badges/age/npm/astro/6.3.1?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/astro/6.2.2/6.3.1?slim=true) |

---

### Release Notes

<details>
<summary>withastro/astro (astro)</summary>

### [`v6.3.1`](https://github.com/withastro/astro/blob/HEAD/packages/astro/CHANGELOG.md#631)

[Compare Source](https://github.com/withastro/astro/compare/astro@6.3.0...astro@6.3.1)

##### Patch Changes

- [#&#8203;16646](withastro/astro#16646) [`15fbc41`](withastro/astro@15fbc41) Thanks [@&#8203;matthewp](https://github.com/matthewp)! - Fixes local images returning 404 on non-prerendered pages when using the generic image endpoint

### [`v6.3.0`](https://github.com/withastro/astro/blob/HEAD/packages/astro/CHANGELOG.md#630)

[Compare Source](https://github.com/withastro/astro/compare/astro@6.2.2...astro@6.3.0)

##### Minor Changes

- [#&#8203;16366](withastro/astro#16366) [`d69f858`](withastro/astro@d69f858) Thanks [@&#8203;matthewp](https://github.com/matthewp)! - Adds a new `experimental.advancedRouting` option that lets you take full control of Astro's request handling pipeline by creating a `src/app.ts` file in your project.

  Today, Astro handles every incoming request through a fixed internal pipeline: trailing slash normalization, redirects, actions, middleware, page rendering, i18n, and so on. That pipeline works great for most sites, but as projects grow you often want to run your own logic *between* those steps — an auth check before rendering, a rate limiter before actions, custom logging around the whole stack. Advanced routing gives you that control.

  When enabled, Astro looks for a `src/app.ts` file in your project. If it finds one, that file becomes the entrypoint for all server-rendered requests. You compose the pipeline yourself using the handlers Astro provides, and you can slot your own logic anywhere in the chain.

##### Enabling advanced routing

```js
// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    advancedRouting: true,
  },
});
```

##### Two ways to build your pipeline

Astro ships two entrypoints for advanced routing: `astro/fetch` and `astro/hono`.

**`astro/fetch`** is a low-level, framework-free API built on the Web Fetch standard. You create a `FetchState` from the incoming request, then call handler functions in sequence. Each handler takes the state, does its work, and returns a `Response` (or `undefined` to pass through). This is the core primitive that everything else is built on:

```ts
// src/app.ts
import {
  FetchState,
  trailingSlash,
  redirects,
  actions,
  middleware,
  pages,
  i18n,
} from 'astro/fetch';

export default {
  async fetch(request: Request) {
    const state = new FetchState(request);

    // Early exits — these return a Response only when they apply.
    const slash = trailingSlash(state);
    if (slash) return slash;

    const redirect = redirects(state);
    if (redirect) return redirect;

    const action = await actions(state);
    if (action) return action;

    // Middleware wraps page rendering; i18n post-processes the response.
    const response = await middleware(state, () => pages(state));
    return i18n(state, response);
  },
};
```

**`astro/hono`** wraps the same handlers as [Hono](https://hono.dev) middleware, so you can mix Astro's pipeline with Hono's ecosystem of middleware (logger, CORS, JWT, rate limiting, etc.) using the `app.use()` pattern you already know:

```ts
// src/app.ts
import { Hono } from 'hono';
import { getCookie } from 'hono/cookie';
import { logger } from 'hono/logger';
import { actions, middleware, pages, i18n } from 'astro/hono';

const app = new Hono();

app.use(logger());

// Auth gate — only runs for /dashboard routes.
app.use('/dashboard/*', async (c, next) => {
  const session = getCookie(c, 'session');
  if (!session) return c.redirect('/login');
  return next();
});

app.use(actions());
app.use(middleware());
app.use(pages());
app.use(i18n());

export default app;
```

Both approaches give you the same power — pick whichever fits your project. If you don't need a framework, `astro/fetch` keeps things minimal. If you want a rich middleware ecosystem, `astro/hono` gets you there with one import.

For more information on enabling and using this feature in your project, see the [experimental advanced routing docs](https://docs.astro.build/en/reference/experimental-flags/advanced-routing/). To give feedback, or to keep up with its development, see the [advanced routing RFC](https://github.com/withastro/roadmap/blob/advanced-routing-stage-3/proposals/0056-advanced-routing.md) for more information and discussion.

- [#&#8203;16366](withastro/astro#16366) [`d69f858`](withastro/astro@d69f858) Thanks [@&#8203;matthewp](https://github.com/matthewp)! - Adds a `consume()` instance method to `AstroCookies`. This method marks the cookies as consumed and returns the `Set-Cookie` header values. After consumption, any subsequent `set()` calls will log a warning, since the headers have already been sent.

  Previously this was only available as a static method `AstroCookies.consume(cookies)`. The static method is now deprecated but kept for backward compatibility with existing adapters.

- [#&#8203;16412](withastro/astro#16412) [`ba2d2e3`](withastro/astro@ba2d2e3) Thanks [@&#8203;0xbejaxer](https://github.com/0xbejaxer)! - Add retry and error event handling for `astro-island` hydration import failures to reduce unrecoverable hydration errors on transient network failures.

- [#&#8203;16582](withastro/astro#16582) [`885cd31`](withastro/astro@885cd31) Thanks [@&#8203;Princesseuh](https://github.com/Princesseuh)! - Adds a new `image.dangerouslyProcessSVG` flag to optionally enable processing SVG inputs. For security reasons, Astro will no longer rasterizes SVG image sources by default in its default image service and endpoint.

  Set `image.dangerouslyProcessSVG: true` to opt back into processing SVG inputs.

  ```js
  // astro.config.mjs
  import { defineConfig } from 'astro/config';

  export default defineConfig({
    // ...
    image: {
      dangerouslyProcessSVG: true,
    },
  });
  ```

  Note that this is a breaking change for users who were previously relying on Astro's default image service to rasterize SVG inputs, but it is a necessary change to improve security and prevent potential vulnerabilities.

- [#&#8203;16519](withastro/astro#16519) [`1b1c218`](withastro/astro@1b1c218) Thanks [@&#8203;louisescher](https://github.com/louisescher)! - Adds support for redirecting URLs in remote image optimization.

  Previously, when a remote image URL meant to be optimized by Astro led to a redirect, Astro would fail silently and ignore the redirect. Now, Astro tracks up to 10 redirects for these images. If any of the redirects are not covered by a pattern in `image.remotePatterns` or a domain in `image.domains`, Astro will fail with a helpful error message.

  In the following example, the first image would be loaded successfully, while the second would lead to Astro throwing an error:

  ```mjs
  export default defineConfig({
    image: {
      domains: ['example.com', 'cdn.example.com'],
    },
  });
  ```

  ```tsx
  {
    /* Redirects to https://cdn.example.com/assets/image.png: */
  }
  <Image
    src="https://example.com/assets/image.png"
    width="1920"
    height="1080"
    alt="An example image."
  />;

  {
    /* Redirects to https://malicious.com/image.png: */
  }
  <Image
    src="https://example.com/bad-image.png"
    width="1920"
    height="1080"
    alt="An example image."
  />;
  ```

  In cases where all redirects to HTTPS hosts should be trusted, the following configuration for `image.remotePatterns` can be used:

  ```mjs
  export default defineConfig({
    image: {
      remotePatterns: [
        {
          protocol: 'https',
        },
      ],
    },
  });
  ```

##### Patch Changes

- [#&#8203;16592](withastro/astro#16592) [`9c6efc5`](withastro/astro@9c6efc5) Thanks [@&#8203;matthewp](https://github.com/matthewp)! - Escapes interpolated values in the dev server redirect HTML template, consistent with how the 404 template already handles them

- [#&#8203;16585](withastro/astro#16585) [`78f305e`](withastro/astro@78f305e) Thanks [@&#8203;web-dev0521](https://github.com/web-dev0521)! - Fixes `z.array(z.boolean())` in form actions incorrectly coercing the string `"false"` to `true`. Boolean array elements now use the same `'true'`/`'false'` string comparison as single `z.boolean()` fields, so submitting `["false", "true", "false"]` correctly parses as `[false, true, false]`.

- [#&#8203;16567](withastro/astro#16567) [`12a03f2`](withastro/astro@12a03f2) Thanks [@&#8203;matthewp](https://github.com/matthewp)! - Fixes deleted content collection entries persisting in `getCollection()` results during dev

- [#&#8203;16595](withastro/astro#16595) [`ce9b25c`](withastro/astro@ce9b25c) Thanks [@&#8203;web-dev0521](https://github.com/web-dev0521)! - Fixes `pushDirective` in the CSP runtime duplicating the new directive once per existing non-matching directive. Calling `insertDirective()` (or otherwise pushing a directive whose name is not yet in the list) now appends it exactly once, and a directive that merges with a later existing entry no longer leaves an unmerged copy behind.

- [#&#8203;16600](withastro/astro#16600) [`94e4b7c`](withastro/astro@94e4b7c) Thanks [@&#8203;web-dev0521](https://github.com/web-dev0521)! - Fixes `Astro.preferredLocale` returning the wrong value when `i18n.locales` mixes object-form entries (`{ path, codes }`) with string entries that normalize to the same locale. The first matching code in the configured `locales` order is now selected, matching the documented behavior.

- [#&#8203;16591](withastro/astro#16591) [`cce20f7`](withastro/astro@cce20f7) Thanks [@&#8203;matthewp](https://github.com/matthewp)! - Uses a consistent generic error message in the image endpoint across all adapters

- [#&#8203;16629](withastro/astro#16629) [`f54be80`](withastro/astro@f54be80) Thanks [@&#8203;g-taki](https://github.com/g-taki)! - Fixes a bug where SSR responses in `astro dev` could crash with `TypeError: this.logger.flush is not a function`.

- [#&#8203;16589](withastro/astro#16589) [`3740b24`](withastro/astro@3740b24) Thanks [@&#8203;ArmandPhilippot](https://github.com/ArmandPhilippot)! - Fixes an outdated code snippet in the documentation for session storage configuration.

- Updated dependencies \[[`354e231`](withastro/astro@354e231)]:
  - [@&#8203;astrojs/telemetry](https://github.com/astrojs/telemetry)@&#8203;3.3.2

</details>

---

### Configuration

📅 **Schedule**: (UTC)

- Branch creation
  - At any time (no schedule defined)
- Automerge
  - At any time (no schedule defined)

🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.

♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 **Ignore**: Close this PR and you won't be reminded about this update again.

---

 - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box

---

This PR has been generated by [Mend Renovate](https://github.com/renovatebot/renovate).
<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0My4xNjAuNyIsInVwZGF0ZWRJblZlciI6IjQzLjE2MC43IiwidGFyZ2V0QnJhbmNoIjoibWFpbiIsImxhYmVscyI6W119-->
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

pkg: astro Related to the core `astro` package (scope) semver: minor Change triggers a `minor` release

Projects

None yet

Development

Successfully merging this pull request may close these issues.

astro-island: no error event, retry, or recovery when hydration import() fails

3 participants